using RAG.Application.Dtos.Rag;

namespace RAG.Application.Services.Interfaces;

/// <summary>
/// RAG问答服务接口
/// </summary>
public interface IRagQuestionAnswerService
{
    /// <summary>
    /// 基于知识库回答问题
    /// </summary>
    /// <param name="request">问答请求</param>
    /// <returns>问答响应</returns>
    Task<RagQuestionAnswerResponseDto> AskQuestionAsync(RagQuestionAnswerRequestDto request);

    /// <summary>
    /// 为流式回答准备（检索 + 上下文拼接），返回上下文与来源，供后续即时流式生成使用
    /// </summary>
    Task<RagPreparationResult> PrepareStreamingAsync(RagQuestionAnswerRequestDto request);

    /// <summary>
    /// 获取知识库中的相似内容（用于调试和验证）
    /// </summary>
    /// <param name="question">问题</param>
    /// <param name="limit">返回数量限制</param>
    /// <param name="threshold">相似度阈值</param>
    /// <returns>相似内容列表</returns>
    Task<List<SimilarKnowledgeDto>> GetSimilarKnowledgeAsync(string question, int limit = 5, double threshold = 0.7);

    /// <summary>
    /// 上传知识内容并向量化存储
    /// </summary>
    /// <param name="request">知识上传请求</param>
    /// <returns>上传结果</returns>
    Task<KnowledgeUploadResponseDto> UploadKnowledgeAsync(KnowledgeUploadRequestDto request);

    /// <summary>
    /// 上传多模态知识内容（图片+文本）并向量化存储
    /// </summary>
    /// <param name="request">多模态知识上传请求</param>
    /// <returns>上传结果</returns>
    Task<KnowledgeUploadResponseDto> UploadMultimodalKnowledgeAsync(MultimodalKnowledgeUploadRequestDto request);

    /// <summary>
    /// 清理知识库数据
    /// </summary>
    /// <returns>清理结果</returns>
    Task<KnowledgeCleanupResponseDto> CleanupKnowledgeBaseAsync();
}
